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ABOUT _THIS_BOOkK 


This manual explains how write to programs to contral devices for computers 
running the GRif Operating System (GRiD-OS). 


This manual assumes that you are an experienced PASCAL and PL/M 
programmer and are familiar with the GRiD-ODS devel opment 
environment. 


If you have not programmed under GRiD-OS before, you may need to 
refer to the following publications: 


o GRiD-DS Reference manual for detailed information on operating 


system calls, semaphores, and file 1/0. 


oO Program Development Guide for information on how to run the 


compilers and utilies and the GRiDDevelop program. 


a Intel PASCAL-84 User’s_Guide for information on the Pascal 


programming language. 


a Intel PL/M-86 User’s Guide for information on the PL/M 


Programming language. 
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EXAMPLE PROGRAM SOFTWARE @ 


This book contains example programs and develop files. Source 
code for these is available on GRiD Central under Software 
Subjects 3.1: Contributed Device Drivers. 
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CHAPTER i: INTRODUCTION TO DEVICES 


Here is a diagram of devices in a sample GRiD computer system: 


Ae GRiD Computer 
P 


eS a = 


Hard Portable Printer 
Disk Floppy Widget 


Figure 1-1. Sample GRiD Computer System 
Printers, plotters, digitizers, video disks, laser printers, 
laboratory equipment, hard disks, floppy disks, bubble memory and 
modems are all physical devices. These devices and others like them 
can be controlled by GRiD software. 
GRiD-OS supports three types of devices: those that have a serial 


interface, those that have a GPIB (IEE-4B8) interface, and the 
internal modem. 


Application pragrams make 1/0 requests to the GRiD Operating System 
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(GRiD-05). GRiD-OS passes the request to a program called a shell 
which passes the request on to a program called the gateway driver. 
The gateway driver actually communicates with the device at the 
hardware level. See Figure 1-2, 
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Figure 1-2. Communicating With Devices 


GRiD supplies three gateway drivers for device 1/0. The serial 
gateway driver is in a file called Serial*Device” and the modem 
gateway driver is in a file called Modem™Device”. The GPIB gateway 
driver is built into GRiD-OS. 


& shell is a program that allows applications to be device 
independent. You can put all device dependencies in the shell. 
Then when a new device is used, the application need not be 
modified. 


STEPS_FOR WRITING DEVICE PROGRAMS 


GRiD supplies ail the software necessary to use many devices. To 
use a device that is not supported by GRiD, or to use the internal 
modem differently from GRiD applications, you may have to write some 
software to cantral the device. 
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PRINTERS 


1. If you don"t require text formatting commands or graphics, you 
Can use a generic printer shell. I+ you do require these 
features, you should write a shell or modify a generic shell. 
Writing a shell is covered in Chapter 3 - "Writing A Sheli". You 
way also need to refer to Chapter 5 or Chapter 6 depending an 
which interface your printer requires. If you write a sheli, be 
sure the final, linked file containing the shell has kind 
“Printer”, 


c. Use GridManager’s CODE-C command to make the shell your current 


printer. 


THE INTERNAL MODEM 


1. Include calls to the modem gateway driver in your application 
program as described in Chapter 4 ~ "Frogramming The Modem 
Gateway Driver". 


2. Activate Modem™*Device™ fram the command line or from your 


Program. See Chapter 2 - "Adding And Removing Devices" for more 
information on this. 


OTHER SERIAL DEVICES 


1. Include calls to the serial gateway driver in your application 
Program for all devices except printers; you must use a shell for 
printers. See Chapter 5 - "Programming the Serial Gateway 
Driver" 


2. Activate Serial™Device™ from the command line or from your 


iS 


Program. See Chapter 2 - "Adding And Removing Devices" for more 
information on this. 


OTHER GPIB DEVICES 


1. If it is acceptable to send all device dependent commands fram 
your application, then you can use a generic GPIB shell. If you 
want your application to be device independent, then you can 
write or modify a shell. Refer to Chapter 3 - “Writing & Shell” 
and Chapter 6 - "Programming The GPIB Gateway Driver". 


2. Activate your shell from the command line or fron your program. 


See Chapter 2 - "Adding And Removing Devices" for more 
information on this. 
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CHAPTER 2: ADDING AND. REMOVING DEVICES 


This chapter provides information on how to add and remove devices from within 
your program. You could also use the Activate and Deactivate command line 
utilities to achieve the same results. These utilities are described in the 
Program Development Guide. 


THE ACTIVE DEVICE TABLE 


The Active Device Table, maintained by GRiD-OS, is a table of 
gateway drivers and device driver shells currently residing in 
memory and available to be used by an application. 


The table associates an ASCII string with the device or shell code; 
this allows an application to attach to the driver by name instead 
of by memory address. 


You can add or remove (also referred to as activate and deactivate) 
gateway drivers and driver shells from this table dynamically. This 
allows you ta save memory by keeping memory resident only those 
drivers necessary at a given time. 


You must activate the modem and serial gateway drivers before using 
them. Because the GPIB gateway driver is in GRiD-O5, it is not 
necessary to activate it. However, you must activate a GPIB shell 
before using it. 


The active device table also allows you to associate a GPIB address 
with a shell when it is added to the table. Because driver shells 
are re-entrant, you can associate the same driver code with devices 
that have different GPIB addresses. This allows you to avoid 
duplicating code. For example, the same driver code can be used for 
a Portable Floppy and an Extra Portable Floppy; only the GPIB 
address need change. 
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ACTIVATING AND DEACTIVATING GATEWAY DRIVERS AND SHELLS FROM YOUR PROGRAM 


You can activate a gateway driver or shell from your program by 

calling a procedure named ActivateDevice. Versions of the procedure @ 
exist for both the Compact and Large models of compilation; they can 

be found in files named Activate Compact*OBJ~ and Activate 

Large*0BJ” on GRiD Central: Software Subjects 3.1 under Contributed 

Device Drivers. The appropriate object file should be linked toa the 
program making the call. 


These procedures use the GRiD-OS call OsAddDevice. Applications can 
use OsAddDevice directly, but the interface to ActivateDevice is 
simpler and easier to use. 


& similar procedure named DeactivateDevice exists in each of the 
object modules and can be used to remove a driver or shell from the 
active device table. 


THE ActivateDevice PROCEDURE CALL 


You must provide information about the attributes of the driver or 
shell code and its location, which can be one of the following: 


o The driver or shell is in a file on secondary storage. 


o The shell code has been linked to the program making the 
ActivateDevice call. 


o The shell has already been activated and you want to use the same 
code for another device. 


The ActivateDevice procedure has the following PASCAL declaration. 


NOTE: This definition is not in an include file. You must type the 
declaration yourself in the interface specification of your PASCAL 
program. 


PUBLIC DeviceProcs; 
PROCEDURE ActivateDevice (path: StringPtr; 
name: StringPtr3; 
VAR entryPoint: BYTES; 
intAddr: BYTE; 
attributes: WORD; 
VAR error: WORD); 


path path is a string used to indicate the location of the 
gateway driver or shell to be activated. If you set 
bit © of attributes (described below) to 0, set path 


to the pathname of the driver or shell file. If you 
set bit 0 to 1, then set path to the device name 
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name 


entryPoint 


intAddr 


attributes 


including back quate (*). If the drives or shell 
code is linked to program {case two), then set path 
to NIL. If path is not NIL, then the ActivateDevice 


procedure autamatically frees the path StringPtr. 


fame is a string that indicates the name that is to 
be put into the active device table. Name should NOT 
have a back quote (*) in front of it. If you want 
the title part of the path parameter to be the name, 
then set name to NIL. If this parameter is not NIL, 
then it is automatically freed. 


If the shell is linked to the program, then set 
entryPoint to the shell main procedure name. If not, 
then this parameter should be a de-referenced NIL 
Pointer. If entrypoint has any value other than NIL, 
then path is ignored. 


intAddr is the interface address (GPIB address) of 
the device. Jf the device is not a GPIB device, then 
set intAddr to NULLBYTE (OFFh). 

Individual bits in this word represent attributes of 
the device. The following bits are defined (bit 0 is 
the least significant bit): 


Description 


Driver location bit. 

IF o, then path is the pathname where 
the driver or shell is located. 

Tf 1, then path is the 

name of am already activated device. 


Visible bit. 

Q- visible; 1 - invisible. 

Invisible devices don’t appear on the file 
farm’s device list. For a device to appear on the 
device list it must be visible and a mass storage 
device. 

This bit should be set to zero. 

Mass storage bit. 

0 — the device is a non mass storage device. 

1 - the device is a mass storage device. 

This bit should be set to zero. 

This bit should be set to zero. 


This bit should be set to zero. 
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“i searcnme o1t. 
Q - the device is searchable 
1 - the device is not software searchable 


(For this to be valid the mass storage bit 
must be 1) Sometimes GRiD-OS searches for files. @ 
For example, if you select a text file froma file 
form, GRiD-OS will search for a file with a kind 
“Run Text”. It will only search in software 
searchable mass storage devices. 

All ather bits in this word are reserved and should be set to 

zero. 


Error The ActivateDevice routine returns an error code in 
this parameter. 


THE DeactivateDevice PROCEDURE CALL 


To deactivate a gateway driver or shell, call the DeactivateDevice 
routine with the name of the device to deactivate; specify the same 
name an application would use to attach to the driver. 


Here is the PASCAL definition for DeactivateDevice. It should also 
be typed in the interface specification. 


PROCEDURE DeactivateDevice (pathName: StringPtr; 
VAR errors WORD); 


Four examples are shown: 

@ Activating the internal modem. 

o Activating the Extra Portable Floppy. 
o Deactivating the modem. 


o Activating a linked driver, 
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o 


ACTIVATING THE INTERNAL MODEM 


It is assumed that that a file named Modem™Device™ exists in the 
Programs subject on a secondary storage device. The ActivateDevice 
routine will search each mass storage device until the file is 
found. 


PROCEDURE ActivateTheMadem; 


CONST 
nullByte = Offh; 
attribute = 80H; 


VAR 
error: WORD; 
nullPtrs “BYTE; 


BEGIN 
nullPtr r= NIL; 
ActivateDevice (NewStringLit (?Modem™Device’’), 
NIL, 
nullPtr*, 
null Byte, 
attribute, 
error); 
END; 


ACTIVATING AN EXTRA PORTABLE FLOPPY 


This example assumes that the Portable Floppy has already been 
activated, 


PROCEDURE ActivateExtraFlappy; 
CONST 


floppyAddr = 
attribute 


{ mass storage, visible, already activated } 


VAR 
error: WORD; 
nullPtr: “BYTE; 


BEGIN 

nullPtr := NIL: 

ActivateDevice (NewStringLlit (Portable Floppy’), 
NewStringLit (’Extra Floppy’), 
nullPtr*, 
floppyAddr, 
attribute, 
error); 
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END; 
DEACTIVATING THE MODEM 


PROCEDURE DeactivateTheModem; 


VAR 
error: WORD; 


BEGIN 

DeactivateDevice (NewStringlit (’‘Modem’), errar); 
{ Remember the backquote!!! } 

END; 


ACTIVATING A LENKED DRIVER 


It is assumed that a generic GPIB driver has been linked to this 
program and that the OsDevice PROCEDURE has been declared PUBLIC in 
the interface specification of this program. 


PROCEDURE ActivateGenericGPIB; 


CONST 
attribute = BOH; 
Address = 28; 
vaR 


error: WORD; 
nuliPtr: “BYTE; 


BEGIN 
nullPtr s= NIL; 
ActivateDevice (NIL, 
NewStringLit (’GenericGPIB’), 
OsDevice, 
Address, 
attribute, 
error); 
END; 
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CHAPTER 3: 


WRITING & SHELL 


@ shell is a program that GRiD-OS calls after an application program requests 
device 1/0. Shells are usually written in the PL/M programming language. 
Shells process the 1/0 request and then pass the request to a gateway driver 
which actually communicates with the device. 


Shells provide device independence by standardizing the interface to 
the gateway drivers. Device independence is important because it 
takes the burden of communicating to different devices away from the 
applications programmer. 


Shells translate generic commands from applications into 
device-specific commands. For example, GRIDWRite includes commands 
for formatting printed text. One such command is the boldface 
command. However, different printers use different control 
characters for boldface. Rather than requiring GRiDWrite to know 
the boldface control characters for every printer, GRiDWrite uses a 
generic printer language which is passed to the shell. The shell 
then translates the generic boldface command into a printer specific 
boidface command. In this way GRiDWrite can be used with a new 
printer by simply creating a new shell rather than changing 
GRiDWrite. 
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PRENTERS 


© 


For users not interested in text formatting cammands or graphics, 
generic printer shells are available for serial and GPIB printers. 
They pass text as received from applications to the gateway driver. 


If text formatting commands or graphics are desired, you can modify 
one of the generic shells. GRiD uses a Universal Printer Language 
that the shell must interpret and translate into printer specific 
commands. See Appendix A for a description of the Universal Printer 
Language. 


Here are the generic printer shells available on GRiD Central under 
Software Subjects 3.0 in the Contributed Programs subject: 


MinimumSerial: 


Protocol: None 
Baud: 300 
Assumes printer has at least a 128 byte internal buffer 


GenericSerialETX/ACK: 


Protacol: ETX/ACK 
Bauds 1200 
Assumes printer has at least a 128 byte internal buffer @ 


Gener icSerial XON/XOFFs 


Protocol: XON/XOFF 
Baud: 1200 
Assumes printer has at least a 128 byte internal buffer 


GenericGPIB: 


Default GPIB address: 21 
OTHER GPIB DEVICES 


Tf the device doesn’t require data translation, and if 
device-specific commands can be done in the application, generic 
GPIB shells are available for devices that use GPIB Service Requests 
and those that don’t. These shells simply pass requests from 
applications to the GPIB gateway driver without translating the 
information into device specific commands. 


If the you need a device specific shell, one af the generic GPIB 
shells can be modified. 


O 
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OTHER SERIAL DEVICES 


Tt is generally not necessary to write or modify a shell for a new 
serial device other than a serial printer. Instead, the serial 
gateway driver can be programmed from the application as described 
in Chapter 5. 


An application performs device I/O by making calls to GRiD-OS. The 
sequence of calls is shawn in the following figure: 


Attach : Detach 


- 


Open Close 


eee] 


Read 


Write 


GetStatus 
| 
SetStatus 


Figure 3-1. GRiD-OS Device 1/0 Calls 
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When GRiD-0S receives an 1/0 call, it passes an 1/0 request to the 
shell. The correspondence between GRiD-O0S calls and 1/0 requests is as 


follows: 

GRiD-OS Call 1/0 Request @ 
Activate = ddInitialize 
asAttach = ddAttach 

OSOpen = ddOpen 
QSRead = ddRead 
OSWrite ss ddWrite 
O5GetStatus = ddGetStatus 
OSSetStatus = ddSetStatus 
OsClose = ddClose 
OsDetach = ddDetach 
Deactivate S ddDeactivate 


Table 3-1. GRiD-OS calls and 1/0 Requests 


The 1/0 requests are actually constant numbers that are defined in the 
PrinterDriver.Inc include file. 


SHELL INTERFACE 


A shell is written as a PROCEDURE in PL/M that accepts three a 
parameters: 


OsDevice: PROCEDURE (request, pParameters, pError) PUBLIC REENTRANT; 
DECLARE request WORD, 


pParamters POINTER, 
pError POINTER; 


Here is a discusian of the parameters passed to the shell: 


request The 1/0 request number passed to the shell by GRiD-OS. 


pParameters A POINTER to a parameter block containing information fram 
the application and GRiD-~OS. 


pError & POINTER to a WORD where the shell can return an error 
code to the application. 
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Procedure Name 


The name of the procedure must be OsDevice. This is because the shell 
will be linked to an assembly language module (JmpDev.Asm*OBJ™) that 
expects this name. The assembly language module serves as a main 
module for the shell; its only purpose is to provide a start address to 
the linker. 


Parameter Block 


The parameter black has this format: 


Parameter Block 


Commect.. 


[node | 


Bata Buffer 


Overflow Block 


dataMod= 


Figure 3-2. The Parameter Block 
Here is the PL/M declaration for the parameter block: 


DECLARE ParamListType LITERALLY *STRUCTURE ( 


connection SELECTOR, 

pBuf ffer POINTER, 

position DWORD, 
length WORD, 

mode BYTE, 

numb BYTE, 

intAddr BYTE, 

pOver flow POINTER) * 5 


Do not modify these parameters except as noted below. 


pBuffer A POINTER to the buffer specified by the application when 
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it made the GRiD-DS call. This buffer contains data for 
ddRead and ddWrite requests or status information for 
ddGetStatus and ddSetStatus requests. 


length The length of the buffer as set by GRiD-OS according to 
the number of bytes requested by the application; it is QO 
updated by the gateway driver to reflect the actual number 
of bytes transferred. 


antAddr The GPIB address of the device with which the application 
" wants to communicate. If the device is serial, this 
parameter can be ignored. 


pOver flow A POINTER to another STRUCTURE of parameters. 
Overflow Block 


The format af the overflow black depends on the gateway driver called 
and the request being passed to it. For all cases except when a 
ddSetStatus is being passed ta a gateway driver, the averflaw block 
will have the following format: 


DECLARE QverFlowType LITERALLY "STRUCTURE ( 


dataMode BYTE, 
EOSchar BYTE, 
secAddr BYTE, 
timedut WORD)? 5 


@ 


dataMade The data transfer mode used in GPIB shells. A serial 
shell can ignore this parameter. 


E0Schar The End Of String character used in GPIB shells. A serial 
shell can ignore this parameter. 

secAddr Not used. 

timeOut timeQut is only used by the GPIB gateway driver. It is 


the length of time the gateway driver should wait before 
giving up on a request. This number is in milliseconds 
i.e@., a timeout duration of six secands would be expressed 
as 6000, 


When a ddSetStatus request is being passed to a gateway driver, the 
format of the overflow block varies for GPIB shells and serial shells. 
For information on serial ddSetStatus, see Chapter 5. For information 
on GPIB ddSetStatus, see Chapter 4. 
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GATEWAY DRIVER INTERFACE 


@ shell communicates with a gateway driver with the OSCallDriver call. 
The OsCallDriver call looks like this: 


OsCallDriver (pathName : BYTES; 


pathName 


level 


request 


paramList 


level : Byte; 

request ; WORD; 

paramList : ParamListType; 
error : WORD; 


The pathname (formatted as a ShortString) of the gateway 
driver. For a serial device, the pathname is ‘Serial. 
For a GPIB device, the pathname is ‘GPIB. 


& value of 1 specifies that this is a low-level driver 
{for a mass storage device such as bubble memory, hard 
disk, or flappy disk), a value of 0 specifies that it is a 
file level driver ‘for devices such as printers, 
PhoneLink, serial devices, or non-disk GPIB devices). 


A word defining the specific activity (such as open, read, 
write) that the gateway driver is to perform on the 
device. This is the dd-request passed by the application 
to the shell. 


The parameter black specifying device characteristics. 


PROCESSING 1/0 REQUESTS 


The body of a typical shell, in outline form, looks like this: 
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IF request = ddInitialize THEN 
Initialize any shell variables. If mecessary, send initialization 
commands to the device using OsCallDriver and a ddWrite request. 


IF request = ddRead THEN 
Read from the device through the gateway driver and put data in 
the application’s buffer. The shell should also translate data 
from the device at this point if necessary. 


IF request = ddWrite THEN 
Write to the device through the gateway driver from the 
application’s buffer. The shell should should translate data into 
a device-specific format at this point if necessary. 


IF request = ddSetStatus THEN 
Set shell characteristics. A typical use of the OsSetStatus call 
is to allow the application to adjust the device timeout. This 
ddSetStatus request resulting from OsSetStatus is not passed on to 
the gateway driver. However, the shell can make separate 
ddSetStatus requests to the gateway driver to set gateway 
characteristics as follows: 


o Service Request Initialization or Selective Device Clear when 
using the GPIB gateway as described in Chapter 6. 


o A serial printer shell can set operating characteristics of the 
serial gateway driver like baud rates, stop bits, etc. In this 
case, the shell should set up an overflow block such as the 
ones used for OsSetStatus discussed in Chapter 5 and pass this 
block and the ddSetStatus request to the serial gateway driver. 


IF request = ddGetStatus THEN 
Pass shell status back to the application. This request is not 
passed on to the gateway driver. 


IF request = ddOpen,ddAttach, ddClase,ddDetach,ddDeactivate THEN 
Do nothing. 


IF request = any other request THEN 
Return error: RequestNotSupported 


OsSetStatus 


You can use OsSetStatus to pass information to the shell from an 
application. The modem and serial gateway drivers are examples of 
sophisticated OsSetStatus implementations. In those drivers, you can 
pass a number of parameters, including rate of transmission, stop bits, 
etc. In the example at the end of this section, OsSetStatus is used 
only to set the device timeout. In that example, the OsSetStatus 
buffer has the following PL/M declaration: 


DEL SetStatusType LIT *STRUCTURE 
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(setStatMoce BYTE, 
setNewTime WORD) *; 


@ OsGetStatus 


The shell should meet the GRiD-OS minimum specifications for 
OsGetStatus but can add user-defined fields. See the GRiD-OS Reference 
Manual for a discussion of OsSetStatus parameters. 
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EXAMPLE GENERIC SERIAL PRINTER SHELL 


This generic serial printer shell has a simple SetStatus function to 
allow an application to adjust the device timeout. This shell uses the 8 
serial defaults for baud rates, stop bits, etc.; the shell could be . 
modified to make ddSetStatus requests to the serial gateway driver. 


$NOLIST LARGE OPTIMIZE(3) 


/* Generic Serial Read and Write Shel} 
Default TimeOut: 5S seconds 
Liza 


GenericSerialDriver: DO; 
$INCLUDE (‘wO*Incs'PlmLit.Inc™Text™) 


/* Include declarations for ParamListType, etc. #/ 
SINCLUDE (PrinterDriver. Inc’Text™) 


/% Initialize the parameters in the Overflow Block %/ 
DCL overflow OverflawType INITIAL (OFFH, OFFH, 
OFFH, SOQOH) ; 


OsDevice: PROCEDURE (request, pParams, pError) PUB REENT; 
DCL request WORD; 
DCL pParams PTR; 
DCL pError PTR; 


DCL error BASED pError WORD; @ 
DCL params BASED pParams ParamListType; 


DCL pSetStatus PTR; 

DCL setStatus BASED pSetStatus SetStatusType; 
DCL StatusBlack SetStatusType; 

DCL getStatus GetStatusType; 

DCL getStatusLength WORD; 


error = 03 
IF request = ddWrite THEN 


IF params.length > 0 THEN 
DO; 
Params.pOverflow = daverflow; 
CALL OSCALLdriver (9(5,’ ‘*Serial’), 0, DOUBLE (ddWrite), 
Oparams, Derror); 
END; 
ELSE 
IF request = ddRead THEN 
IF params.length > 0 THEN 
DO; 
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params. pOverflow = doverflow; 
CALL OSCALLDriver (9(5,’ ‘Serial’),0,DOUBLE (ddRead) : 
Qparams, error); 
END; 
ELSE 
IF request = ddGetStatus THEN 
Da; 

‘* Device is OPEN, update Access allowed, all other © 4/ 
CALL SETB (0, @getStatus, SIZE (getStatus)); 
getStatus. open = OFFH; 
getStatus.access = 4; 

IF params.tength < SIZE {getStatus) 
THEN getStatusLength = params. length; 
ELSE getStatusLength = SIZE (getStatus); 
CéLt MOVE (agetStatus, params. pBuffer, getStatusLength) : 
END: 
ELSE 
If request = ddSetStatus THEN 
DO; 
pSetStatus = params.pBuffer; 
overflow.timeOut = setStatus.setNewTime; 
END; 
ELSE 


/* Ignore other valid requests, return error if not valid ¥/ 


IF NOT ((request = ddOpen) OR 
(request = ddInitialize) OR 
(request = ddClose) OR 
(request = ddDetach) OR 
(request = ddAttach) OR 
(request = ddTruncate) OR 
(request = ddDeactivate)) THEN 


error = notSupperted; 
END; 


END; /* Module x/ 
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CHAPTER_4: PROGRAMMING THE MODEM GATEWAY DRIVER 


If GRibTerm, GRiDVT100, GRiD3101, GRiDAccess, or GRiDManager do not satisfy 
your communication requirements, you'll need to write a program that sets the 
modem options yourself. 


GRiD provides a modem gateway driver called Modem™”Device”, through which you 
can control the madem and send and receive data. 


The madem gateway driver supports voice made, where you can talk through the 


GRiD handset and listen an the speaker, and data mode, where the madem 
communicates with a remote modem. 


To write a program that reads from and writes ta the modem gateway 
driver: 


1. Add Madem*Device™ as an active device. 
2. Attach to the modem using GsAttach with pathname = ‘Modem. 
3. Open the modem using OsQpen. 


4. Program desired operating characteristics (bits/sec, stop bits, 
etc) using OsSetStatus as described in this chapter. 


5. If you are originating the call, use OsSetStatus to dial a phone 
number and to establish a connection. If you are answering, use 
GsGetStatus ta obtain an identification number for the ring 
semaphore. The gateway driver signals the ring semaphore when it 
detects an incoming call. You should wait for the signal using 
OsWait, then use QsSetStatus to connect with the remote modem. 
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&. Read from and write to the modem using OsRead and OsWrite. 
7. Close and detach the medem using OsCliose and OsDetach. 


&. Remove the modem from the active device table. 


The OsSetStatus call has this PASCAL declaration: 
PROCEDURE OsSetStatus (comm:WORD; VAR pBuffer: BYTES; 
Jength: WORD; VAR error: WORD) 5 
conn The connection number returned from an OsAttach call. 
pBuffer A pointer to a parameter block. The parameter block has a 
mode byte followed by a varying number of parameter bytes. 
See Figure 4-1. 
length The length af the parameter block including the mode byte. 


error A WORD where an error code is returned. You can examine 
this word te determine if the call was successful. 
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@ 


The parameter block has this format: 


Fest fer 


Parameter 
Bytes 


Figure 4-!. The Parameter Block 


The following section describes the modes that can be used to 
program the modem gateway driver. 


MODE 0 - RETURN TO DEFAULT SETTINGS 


A parameter block with mode byte = © and no parameter bytes causes 
the modem gateway driver to return ta a default state: 


Bits/Sec 

Data Bits 

Stop Bits 

Parity 

Connection Timeout 
Character Timeout 
Receive Queue 
Originate/Answer 
Dial Tone Timeout 
Disconnect Timeout 


Default Value Made To Change 
1200 7 
8 t 
2 1 
None 1 
30 Seconds 2 
Forever 2 
Internal 4 
Automatic aS 
15 Seconds a9 
3.5 Seconds ag 
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MODE 1 - SET OPERATING VALUES 


i 
H 1) Protocol! Char. 
' 


i Bits/ { Stop 


Bits Parity 


Protacol 


Bits/Char. 


Stop Bits 


Parity 


Asynchrenus 


onouw 
1 


~ 5S bits/char. 
6 bits/char. 
~- 7 bits/char. 
- 8 bits/char. 


= 1 stop bit 
- 1.5 stop bits 
- 2 stop bits 


ate 


- None 
- €ven 
Odd 

- Mark 
- Space 


BUNS 
1 


MODE 2 - SET TIMEQUT VALUES 


CharTimeOut and 


CharTimeOut 


Connect TimeOut 
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ConnectTimeQut are WORD values. 


The number of milliseconds the gateway driver should 
wait for a character before issuing a TimeQut error. 
If you set CharTimefut to zero, then the gatway 
driver waits until the requested number of bytes are 
available. 


The number of milliseconds the gateway driver should 
wait for a handshake from the other modem after a 
go-ta-data (mode six) command. 


oO 


@ 


MODE 3 — FLUSH RECEIVE FIFO BUFFER 


Mode 3 can be used to remove spurious characters fram the receive 
FIFO buffer. 


MODE 4 - SET USER DEFINED RECEIVE FIFO BUFFER 


fifoPtr A POINTER to an input buffer in the application 
program. 
fifoLength The length of the new buffer. 


Use this mode when you want the gateway driver to use a Larger input 
buffer than the driver*s internal 32 character FIFO buffer ta avaid 
overflow and loss of data. You should not access the new buffer 
directly; but should use the OsRead call instead. 


MODE 5S - DISESTABLISH DATA CONNECTION 


Use made 5 te exit data mode. Voice mode will be entered if it has 
been enabled with mode 45; otherwise an idie state will be entered. 
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MODE 6 — ESTABLISH DATA CONNECTION 


Use mode & to go to date mode and attempt to handshake with the 
other modem. If this does not happen within the connection timeout 
period (specified in mode 2), a TimeOut error will be returned. You 
can determine the type of handshake with made 43. 


MODE 7 - SET BITS/SECOND 


- 300 Bits/Sec. 
- 1200 Bits/Sec. 


MODE 41 - TAKE PHONE OFF HOOK 


Use mode 41 to cannect to the phone line. The off-hook function is 
also done automatically in mode 44, 


MODE 42 - PUT PHONE ON HOOK 


Use mode 42 to disconnect from the phone line. You cannot reconnect 
to the phone line for a time called the disconnect delay. This 
delay ensures that the phane is really hung up. The disconnect 
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delay can be set with made 49. 


MODE 43 - SET ORIGINATE OR ANSWER 


Originate 


Originate or Answer = 0 —- Automatic 

t - Originate 

2 - Answer 

255 - Don’t Change 


Use mode 43 to control the type of handshake used in a made 6 
command. If automatic is chosen, the gateway driver will use 
originate made if the phone has been dialed since the last off hoak 
command, else answer mode will be used. 
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MODE 44 - DIAL PHONE NUMBER 


Touch @ 


: ' 
: : 
44 } Tone Length Phone Number i 
' ‘ 
H H 


Mode 44 causes the modem gateway driver to dial a number. If the 
phone is nat off the haok (see mode 41), then an off haok command is 
automatically executed before dialing. 


TouchTone @ BOOLEAN that indicates if a touchtone or pulse 
dialing is being used. Use TRUE for a touchtone 
phone. 

Length The length of the phone number that follows. 


Phone Number The phone number to be dialed. The number should be 
in ASCII form. The fatlawing characters are valid: 


Character Interpretation 
0-9 Same as on a phone 
5 Qne second delay 
® Wait for-a dial tone 
x Same as on a touchtone phone 
# Same as on a touchtaone phone @ 
space, parentheses, dash ignored 


Spaces, parentheses and dashes can be used to make the number more 
readable but are ignored by the gateway driver. However, they must 
be included when determining the length parameter. 


MODE 45 - ENABLE VOICE MODE 


Use made 45 to enable voice mode. When voice made is enabled, voice 
mode will be entered when data mode is exited with mode 5S. 
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MODE 44 - DISABLE VOICE MODE 


If voice mode is disabled, an idle state is entered when exiting 
data mode using mode 5S. 


MODE 49 - SET TIMEQUT VALUES 


} 
i H H 
49 | DialTone Timeout |! DisconnectTimeQut } 
1 1 ! 


DialTane Timeout and DisconnectTimeout are WORD values. 


DialTone Timeout The number of milliseconds the gateway driver 
should wait for a dial tone when a caret (*) is 
encountered in a phone number. If this time is 
exceeded, a TimeOut error is returned. 


Disconnect TimeOut The number af milliseconds the gateway driver 


should delay before allowing a reconnection 
(mede 41). 


MODE SO - SET SPEAKER VOLUME 


u 
<x 


Volume - Speaker Off 


255 - Maximum Volume 


This mode lets you adjust the volume of the speaker. 
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THE OsGetStatus_CALL 


The OsGetStatus call obtains information about the current state of 
the modem gateway driver. This call is described in the GRiD-0S 
Reference Manual but the sletus record format citfers for every 
device. The status record for the modem gateway driver hes this 


format: 


StatusType = RECORD 


apen 


access 


seek 
filePosition 


numCharsinFifa 


synchDetect 


connection 
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open: BOOLEAN; 
access: BYTE; 
seek: BYTE: 


fileFosition: LONGINT; 
numCharsInFifo: LONGINT; 


syncDetect: BOOLEAN; 
connection: BYTE; 
usartStatus: BYTES 
modemStatus: BYTE; 
RingSID: WORD; 


END; 


If the modem gateway is attached, this BOOLEAN is 
TRUE. 


This BYTE is bit-mapped to indicate the type of 
access allowed. It will always be set for read and 
write access. See the GRi anual for 
a description of the bit~map. 


This BYTE is always 0. 
This LONGINT is always 0. 


This LONGINT contains the number of characters 
currently in the recieve buffer. 


This BOOLEAN is always FALSE. 


This contains the current status of the connection: 


connection = 0 - No connection established 
Off hook, voice mode. 

Off hook, data mode. 

Not used. 


- Carrier was last. 


Q 
L 
2 
3 
4 


usartStatus 


modemStatus 


ringSID 


This byte allows you to determine if errors have 
occured on the interface. The usartStatus byte is 
bit-mapped as follaws: 


MSB LsB 
765432190 
xPFOQUX xx 


where: P marks the bit position for parity error. 

.F marks the bit position for framing 
error. 

QO marks the bit position for overrun 
error. 

U marks the bit pasitian for underrun 
error. 


A ane (1) in a bit position means that error has 
occured. 


This byte allows you to determine the state of 
certain signals on the interface. The modemStatus 
byte is bit-mapped as follows: 
NSB LSB 
765SASZ21I0 
xxx Cx Dx x 
where: C marks the bit position for Clear To Send 
(CTS) 


D marks the bit position for Dial Tone 
Detect 


A one (1) in a bit position indicates that signal 
is active. 


This WORD contains the ring semaphore 
identification number. The semaphore will be 
signaled when the ring indicator line is active. 
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This is an example of a program that originates communication with a 
remote madem. It does the necessary setup and then reads a 
character from the modem and writes it back. It then does the steps 
necessary to clean up. 


NOTE: Although this program does not perform error checking after 
GRiD-OS calls, you should include error checking in your code to 
improve reliablity. 


S$DEBUG COMPACT NOLIST 

MODULE Main; 

$INCLUDE (*wO"incs *Common.inc™text™) 
$INCLUDE (*wO‘incs *ConPas.inc*text™) 
INCLUDE (‘wO‘ines ‘OsPasProcs.inc*text™) 
SINCLUDE (‘wO*incs ‘OsPasTypes.inc™text™) 
$INCLUDE (‘wO*incs ‘WindowProcs. inc*text™) 
$INCLUDE (*wO'incs *WindowTypes. inc™text™) 
$LIST 

PROGRAM Main; 


CONST deviceName “todem* 5 


tempNumber AgAsSalZ12"5 
TYPE NumberType = RECORD 
modes CHAR; 
touchtone: BOOLEAN; 
length: CHAR; 
numbers PACKED ARRAY Ci..10] OF CHAR; 
END; 
VAR modemIDs WORD; 
ches CHAR; 
ParameterBlock: PACKED ARRAY [1..91 OF CHAR; 
pathName: PACKED ARRAY E1..7] OF CHAR; 
reserved: Byte; 
error: WORD; 
Phone: Number Type; 
actual: INTEGER; 
BEGIN 
attach tay the: modem: ==—SsSe st ssn rt 3 
pathName deviceName; 
pathWamelii CHR (6) 3 ( Device name is 4 characters 3 
reserved 0; 


macemID := OsAttach (pathName, oldFileltode, reserved, 
updateAccess, error); 


(smears Gpenkthe Modem) -Awssecen SS aa eee 3 
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OsOpen (modemID, 1, error); 


- now establish same appropriate Modem settings --} 


ParameterBlock£1] := CHR); { mode byte } 
ParameterBlack[2] CHR(1)5 € async } 
ParameterBlock[3] CHR (8); € 8 data bits } 
ParameterBlock(4] CHR (3) 5 € 2 stop bit } 
ParameterBlock(£5] := CHR(1); { even parity } 


OQsSetStatus (mademID, ParameterBlock, 5, errar); 


-- set bits/sec ——— 


ParameterBlock[1] := CHR(7); € mode byte > 
ParameterBlack[2] := CHR(5S)3 { 300 Bits/Sec } 


OsSetStatus (modemID, ParameterBlock, 2, error); 


{erposssseoe turn the speaker up ~-~------------------------ = 2 
ParameterBlockl1]} := CHR(S0)3 { mode byte } 
ParameterBlock£2] := CHR(255)3 < volume byte } 


OsSetStatus (modemID, ParameterBlock, 2, errar); 


{-on-oommennm dial the number —------—~—~ nnn nnn enn nn 3 
Phone.mode := CHR(44)5 { mode byte + 
Phone.touchtene := TRUE; € tauchtone } 
Phone.length := CHR(10)5 { # length 3} 
Phone.number := tempNumber; { number } 


OQsSetStatus (modemID, Phone, 13, error); 

{------~---~ go to data mode -----------------—--------------} 
Parameter Block£1] := CHR(4); { mode byte } 
OsSetStatus (modemID, ParameterBlock, 1, error); 


Seer turn the speaker off -o-------ma—en nnn nnn} 


ParameterBlockl1] := CHR(50)3 € made byte } 
ParameterBlock£2] := CHR(O); { volume byte } 


QsSetStatus (modemID, ParameterBlock, 2, error); 
foomoerom---— read a CHAR fram the madem -----~--~-------~~— rats 


actual i= OsRead (modemID, ch, 1, error); 
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{eccca------ write a CHAR ta the modem — 
OsWrite (modemID, ch, 1, error); 

{Sowers er aa disestablish data made ---------<9 nnn n nnn} 
Parameter Blochk£1] := CHR(S) 3 { mode byte } 


OsSetStatus (modemID, ParameterBlock, 1, errar); 


(SsSrcss oS put phone on hook — 


ParameterBlock£1] := CHR(42); { mode byte 


OsSetStatus (modemID, ParameterBlack, 1, error); 


-- clase the modem — 
GsCiose (mademiD, error); 
{eeccece---- detach from the modem ----——omeeer enna 3 
OsDetach (modemID, error); 
OsExit (0); 


END 
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sName: Modem Example 
rPrefix: Example 


:Sources:* 
ModemExample.Pas 


sListings: 

‘west? 
Objects: 
"a" OBd * 


Controls Yes w/Debug: DEBUG 
sLink: 


Link ‘w*OBd *ModemExample.Pas~GBJ~, ‘w "Libs ‘CompactSystemCal]s*Lib” 
TO ModemExample™RUN® BIND SEGSIZE (STACK (+1500)) NOPRINT 


sTest: 
Activate ‘w*Programs ‘Modem™Device~ 
ModemEx ample 
Beactivate ‘Modem 


:Debug: 
& Debug ModemExample 


:Command Line: 
Devel apmentExecutive 


:GridManager: 
Gri DHanager 
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This chapter assumes you are familiar with the RS-2320 serial 
communications standard, However, a short review of some relevant 
concepts follows. 


In the RS-232€ interface, there are two kinds of communication 
eguipment - Data Terminal Equipment (DTE) and Data Communication 
Equipment (DCE). DTE generally are the source ar destination of 
communication such as terminals or computers. DCE are usually 
devices that provide communication services, such as a modem. See 
Figure 5-1. 
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GRiD $ 
Computer Modem 


GTE BCE 


Telephone Sustem 


nce OTE 
Hedem Computer 
Figure 5-1. The Relationship Between DTE and DCE 


The transfer of data between a DTE and-a DCE is cantrolled by 


certain signals: @ 


Signal Direction 
Request to Send (RTS) DTE te DCE 
Clear to Send (CTS) DCE to DIE 
Data Terminal Ready (DTR) DTE to DCE 
Data Set Ready (DSR) DCE to DTE 
Data Carrier Detect (DCD) DEE ta DTE 
Ring Indicator (RI) DCE to DTE 


Table S-t. Handshaking Signals 


The GRID serial port provides an RS-232C compatible interface. The 
computer has a serial connector (Canon 2DE19S) an the rear which has 

19 pins instead of the standard 25. The six pins not represented 

are used for a secendary channel but few devices use this feature. 

GRID manufactures cables {model #6100) ta provide a 19 pin to 

standard 25 pin connector. @ 


The GRiD computer is wired as a DIE (Data Terminal Equipment). 
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Therefore, special cables may need to be fabricated in order to 
connect the computer directiv to ather devices that are also set up 


as DTE. 


SERIAL CONNECTOR 


The serial connector has the following pinout: 


PIN FUNCT ION In/But, PIN FUNCTION In/Qut 
a Shield 2 TxD Qut 
3 Rub In 4 RTS Out 
5 cts In? 6 DSR In 
7 Legic Gnd a Carrier Detect In 
a. TxD Reference Out 10 RxD Reference In 

ii Txt In 12 DIR Out, 

13 Ring Indicator In 14 -LOV DC 2 100mA Out 

15 TxC Reference Out 16 *TxC/Speed Select Out 

17 RsC Reference In 18 Ref In 

19 +10V DC ® 1ihumA Out, 


NOTE: The voltage source circuits should be used only for testing. 


Table 5-2. Serial Connector Pinout 


RS-423 AND RS-422 COMPATIBILITY 


RS-423 and R§-422 are extensions to RS-232 that allow higher signal 
rates, greater distances between stations, and impraved noise 
immunity. Both standards specify that incoming signals should be 
evaluated differentially. RS5-422 further specifies that signals 
should be balanced. Balancing is a technique that requires two 
conductors per circuit but results in better performance. 


The GRiD serial interface supports the RS-425 standard and a subset 
of the RS-422 standard. RS-422 balanced lines are available for 
TxD, RxD, TxC and RxC. RS-423 compatibility can be attained by 
grounding the RxC and RxD reference lines. 


SERIAL RING SEMAPHORE 


Upon initialization, the serial gateway driver creates the serial 
ring semaphore. The gateway driver signals this semaphore whenever 
the ring indicator circuit is active (if ring interrupts are 
enabled). An application program can do an OsWlait on the semaphore 
and allow other processes to run while it is waiting for a ring 
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indicator signal. You obtain the identification number for the 
serial ring semaphore using the OsGetStatus call. 


1. Add Serial“Device™ as an active device. 


2. Attach tau the serial gateway driver using OsAttach with filename 
= ‘Serial. 


3. Open the serial gateway driver using OsQpen. 


4. Program desired operating characteristics (bits/sec, stop bits, 
etc) using OsSetStatus. 


5. Use OsSetStatus to establish a connection with the other device. 


&. Read from and write to the serial gateway driver using OsRead and 
OsWrite. 


7. Clase and detach the serial gateway driver using OsClase and 
OsDetach. 


@. Remove the serial gateway driver from the active device table. 


ROGRAMMING THE SER 


If you are writing a serial printer shell, you should follow the 
steps outlined in Chapter 3 with the following additions: 


o In the ddInitialize section of the shell, the shell should add 
serial to the list of active devices as covered in Chapter 2. 


co In the ddOpen section of the shell, the shell can make ddRequests. 
to the serial gateway driver using OsCallDriver ta program 
operating characteristics and ta establish a data connection. in 
this case, the overflow block would have the same format as the 
OsSetStatus buffer covered in this chapter. 


o In the ddDeactivate section of the shell, the shell should remave 
serial from the list of active devices as covered in Chapter 2. 
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The OsSetStatus call has this PASCAL declaration: 
PROCEDURE GsSetStatus (conn:WORD; VAR pBuffers BYTES; 
Tength:WORD; VAR error: WORD): 
conn The connection number returned from an GsAttach call. 
pBuffer A painter to a parameter block. The parameter block has a 
mode byte followed by a varying number of parameter bytes. 
See Figure 5-2. 


length The length of the parameter block including the mode byte. 


error A WORD where an error code is returned. You can examine 
this word to determine if the call was successful. 


The parameter block has this format: 


PEP ier 
mode bute 


Parameter 
Bytes 


aan 


Figure 5-2 The Parameter Block 
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OsSetStatus_MODES 


MODE 0 —- RETURN TO DEFAULT SETTINGS 


A parameter block with mode byte = 0 and no parameter bytes causes 
the gateway driver to return to a default state: 


Default Value Mode To Change 


Bits/Sec 1200 7 
Data Bits 8 i 
Stop Bits 2 1 
Parity None t 
Connection Timeaut 30 Seconds 2 
Character Timeout Forever 2 
Receive Queue Internal 4 
Required For Go-To-Data CTS, DCD 40 
Ring Interrupt Enabled 61 
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MODE 1 - SET OPERATING VALUES 


H t { Bits/ i Stop ‘ 
t 1 {Protecel! Char. i Bits | Parity 
' \ 


1 
e 


Protocol Asynchronus 


Dae ou 
1 


Bits/Char. 5S bite/char. 
~ 6 bits/char. 
7 bits/char. 
8 


bits/char. 


u 


Stop Hits stop bit 
S stop bits 


stop bits 


aed 
1 
hee 


Parity = 


PUNKS 
' 
o 
a 
a 


NOTE: Mark and space parity are only allowed with less than eight 
bits/character. , 


MODE 2 ~ SET TIMEOUT VALUES 


CharTimeQut and ConnectTimedut are WORD values. 


CharTimeOut The number of milliseconds the gateway driver should 
wait for a character before issuing a TimeOut error. 
If you set CharTimeQut to zera, then the gatway 
driver waits until the requested number of bytes are 
available. 


ConnectTimedut The number of milliseconds the gateway driver should 
wait for a handshake from the other device after a 
go~to-data (mode six) command. 
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MODE 3 - FLUSH RECEIVE FIFO BUFFER 


Mode 3 can be used to remove spurious characters from the receive 
FIFO buffer. 


MODE 4 - SET USER DEFINED RECEIVE FIFO BUFFER 


' ' 


: : 
H H 
t 4ot fifoPtr i fifaLength H 
Hy i } t 
fifoPtr A POINTER to an input buffer in the application 
program. 
4ifoLength The length of the new buffer. g 


Use this made when you want the gateway driver to use a larger input 
buffer than the driver’s internal 32 character FIFO buffer to avoid 
overflow and loss of data. You should not access the new buffer 
directly; but shauld use the OsRead call instead. 


MODE S - DISESTABLISH DATA CONNECTION 


Use made 5 to exit data made. The driver will drop the DTR and RTS 
lines. 
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MODE 6 ~ ESTABLISH DATA CONNECTION 


Use mode 6 to go to data mode and attempt to handshake with the 
The driver will set the RTS and DTR lines active and 
If this does not 


other device. 


wait for DED and CTS to go active {see mode 40). 


happen within the connection timeout period {specified in made 2), a 
TimeOut error will be returned. 


MODE 7 - SET BITS/SECOND 


: 
1 7 : Speed 3} 
Speed =0 - 50 Bits/Sec. 
ae a 
i se 110 
Sas 134.5 
4 = 150 
pe 0 ¥S00) 
& - 6400 
ete 1200 
a=. = 1800 
9 ~- 2000 
10 - 2400 
LS 3400 
120-4800 
13. - 7200 
14 - 9400 
iS - 19200 
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MODE 40 - SIGNALS REQUIRED TO COMPLETE A GO-TO-DATA COMMAND 


Mode 50 allows you to control whether CTS or DCD, or both, must be 
active to complete a go-to-data command (mode = 6). The default is 
that both CTS and DCD must be active. The mask byte is used to 
specify which signal{s) are to be affected by this command. The 
data byte is used to specify whether the signal(s) are required or 
not. . 


The mask and data bytes are both bit-mapped as follows: 
MSB LSB 
76543210 
wenCx Den x 
where "C" marks the bit position far the CTS signal and "D" marks 
the bit position for the DCD signal. You should set the bit 
position(s) in the mask byte to one for the signal(s) to be changed S} 


and set the bit position(s) in the data byte te one to indicate 
which signal(s) need be present to complete a go to data command. 


MODE 41 - ENABLE/DISABLE RING INTERRUPT 


1 1 
H H 
i 64 { Option { 
i H H 
Option byte = 0 - Disable Ring Interrupt 
1 - Enable Ring Interrupt 


Mode 41 tells the driver whether or not ta generate an interrupt 
when it detects a ring indicator signal. Some devices may not have 
the capability to drive the ring indicator line and will simply keep 
it active, thus reducing performance by causing unwanted interrupts. 
You should disable the ring interrupt in that case. 
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THE OsGetStatus CALL 


The OsGetStatus call obtains information about the current state of 
the serial gateway driver. This call is described in the GRiD-OS 
Reterence Manual but the status record format differs for every 
device. The status record for the serial gateway driver has this 
format: 


StatusType = RECORD 


open: BOOLEAN; 
access: BYTE; 
seek: BYTE; 


filePasition: LONGINT; 
numCharsInFifo: LONGINT; 


syncDetect: BOOLEAN; 
connection: BYTES 
MocemControl: BYTE; 
unused: BYTE; 
RingSID: WORD; 
END; 
open If the serial gateway is attached, this BOOLEAN 


will be TRUE. 

access This BYTE is bit-mapped to indicate the type of 
access allowed. It will always be set for read and 
write access. See the GRiD-05 Reference manual for 
a description of the bit-map. 

seek This BYTE is always 0. 

filePosition This LONGINT is always 0. 


numCharsInFifa This LONGINT contains the number of characters 
currently in the recieve buffer. 


synchDetect This BOOLEAN is always FALSE. 
connection This cantains the current status af the connection: 
connection = 4 - Carrier was last. 


2 - Connection established. 
@ — No connection established. 
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modemContral This byte allows you to determine the if certain 
signals are active on the interface. The 
modemControl byte is bit-mapped as tallows: @ 


MSE LSB 


where: D marks the bit position for DCB 
C marks the bit position fer CTS 
Ro marks the bit position for NSk 


A one (1? in a bit position indicates that signal 
is active. 


ringSID This word contains the ring semaphore 
identification number. This semaphore will be 
signaled when the ring indicator line is active and 
ring interrupts are enabled. See QsSetStatus mode 
al. 
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PROGRAMMING THE SERIAL GATEWAY DRIVER EXAMPLE 


This i¢ an example of a program that communicetes with another 


device using the serial port. 1t does the necessar, 


reads a character and writes it back. It then does tne steps 


necessary ta clean up. 


getup and then 


NOTE: Although this prog: an dues not cerform error checking atter 
GRiP-OS calis, you should :nclude error checking routines in your 


code to improve reliability. 


SDEBUG COMPACT NOLIST 

MODULE Main; 

SINCLUBE (*w0 ‘ines ‘Common.inc™text™) 
SINCLUDE (*wO'ines "CanPas.inc*te:t*) 
SINCLUDE (‘wo'ines *OsPasProcs.inc*text™) 
SINCLUDE ("wO'incs GsPestypes.inc*text™) 
SLIST 

PROGRAM Mains 


CONST deviceName = ‘Serial’; 
VaR SerialID: WORD; 
chr CHAR: 
ParameterBlock: PACKED ARRAY £1..9] OF CHAR; 
pathname: PACKED ARRAY C(1..9] OF CHAR; 
reserved: Byte; 
error: WORD; 
actual: INTEGER; 
BEGIN 
{------~-~-— attach ta the serial gateway -—--~----------~---~ 3 
pathName eviceName; 
pathNameliJ HR (7) 5 { Device name is 7 characters } 
reserved H 


SerialID := QsAttach (pathName, oldFileMode, reserved, 


updateAccess, error); 


C 


OsOpen (serialID, 1, error); 


{---- now establish some appropriate serial driver settings -} 


3 


ParameterBiock£1] 2= CHR{1); { made byte } 


ParameterBlock£2] 
ParameterBlock(33 


CHR (1); € async 
CHR (8); {9 data bits } 


z 


ParameterBlock£4] := CHRi3); {2 stop bit } 
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S-t3 


ParameterBlock(S] := CHR(1); { even parity } 


OsSetStatus (SerialID, ParameterBlock, 5, error); 


i a ea rea Set  bits/Secsa=s oS Smor corneas or ek ee 3 
ParameterBlack£1] = CHR(7)3 { mode byte > 
ParameterBlockC2] := CHR(S)3 { 300 Bits/Sec 3 


OsSetStatus (SerialID, ParameterBlock. 2, error); 
‘feesssa==—= gota dabaymode-Ss<cs=s-ScSc satire } 
ParameterBlock[1] := CHR(4); { mode byte } 


GsSetStatus (SerialID, ‘ParameterBlock, 1, errar); 


OsRead (SerialID, ch, 1, error); 
oderalererintpct! weite a CHAR to the serial gateway ~------------} 
OsWrite (SerialID, ch, !, error); 


- disestablish data made ------------------------} 


ParameterBlock€17 := CHR(S); “‘{ made byte + 
OsSetStatus (SeriallD, ParameterBlack, 1, errar); 
{e=hesea =< ellose ‘the: serial igateway:t-ssse seo rar 3 


OsClose (serialiD, error); 


~ detach from the Serial gateway 
OsDetach (Serial1D,error); 
OsExit (0)5 


END 
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SERIAL EXAMPLE 


sName: Serial Example 
Prefix: Example 


:Sources: 
SerialExample. Pas 


Listings: 
“Ww LST" 
Objects: 
"4 "OBY * 


sControls Yes w/Debug: DEHUG 


sLink: 
Link ‘w'OBJ"Serialf;ample.Pas*ORJ”, *w "Libs “CompactSystemCalls*Lib” 
TQ SerialExample*RUN™ BIND SEGSIZE (STACK i+15u0)) NOFRINT 


:Test: 
Activate ‘w*Programs ‘Serial *Device™ 
SerralExample 
Deactivate ‘Serial 


?Debug: 
Debug SerialExample 


:Command Line: 
Devel opmentExecutive 


2GridManager: 
GriDManager 
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The General Purpose Interface Bus (GPIB) is a parallel interface 
used to transmit byte-wide data. At GRID, the interface is used for 
disk drives, printers, and plotters. Since the bus is arbitrated, 
many devices can be hooked up simultaneously and each device has a 
unique address. The GPIB supports addresses ranging from 0 to 31. 


The interface supports three kinds of devices: Controllers, Talkers 
and Listeners. A Controller is a device that arbitrates the bus; 
talkers write data onto the bus; and Listeners only receive data. 
Some devices may combine the functions. A computer running GRiD-OS 
is a Controller but aiso has Talker/Listener capability. 


Data transfer on the bus is arbitrated by the Controller. The 
controller first places the addresses of a Talker and Listener(s) on 
the bus before each message. The messages can either be transmitted 
a byte at a time or in blocks. Handshaking on the bus ensures that 
Talkers send at a rate compatible with Listeners and there is a 
signal called EQ! (End or Identify) that indicates when a message is 
complete. 


Some devices can interrupt the Controller. This occurs on a line 
called Service Request (SRO). After the interrupt, the Controller 
initiates a process called a Serial Poll to determine which device 
requested service. 
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The GPIB gateway driver transmits date in two modes: low speed and @ 
high speed. In the low speed mode (sometimes calied the interrupt 
mode), the gateway driver transmits data a single byte at a time and 
checks after every byte to see if the transmission has been 

terminated. Termination can occur one of five ways: 


o The number of bytes requested has been transferred. 


o The sending devite sent a special byte called the end of string 
(EOS) character. For example, a digitizer might send a carriage 
return after each coordinate has been transmitted over the bus. 
The EOS character is device dependent and can be specified to the 
GPIB gateway driver. If the device doesn’t have an EQS character 
or if you want to disable this feature, the EQS character should 
be specified as OFFH when programming the gateway driver. 


o The other device indicated it was finished by asserting the EOI 
line on the bus. 


o The request timed out. 

Oo An error occured on the GPIB bus. 

In the high speed mode (sometimes called the DMA mode), the gateway 
driver transfers blocks af data to or from a special address in 

memory; special timing is implemented to speed up the transfer. 
Termination can occur one of four ways: e@ 


co The number of bytes requested has been transmitted. 


o The other device indicated it was finished by asserting the EOI 
line on the bus. 


o The request timed out. 

oO An error occured on the GPIB bus. 

Because there is no EOS concept in the high speed mode, you should 
use the low speed mode whenever an EOS function is desired and the 
high speed mode otherwise. 

If you use the low speed mode, you can pragram the amount of time 
the driver should wait before issuing a request timed-out error. In 


the high speed mode, the timeout duration is fixed at five seconds 
because a hardware timer is used. 
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DATA STRUCTURES 


Three main data structures are important to a programmar interested 
in writing a GPIB shell: a parameter block and two kinds of overflow 
blocks. 


PARAMETER BLOCK 


The parameter block has this PL/M declaration: 


DCL ParanListType LITERALLY *STRUCTURE ( 


connection SELECTOR, 
pRuffer POINTER, 
pasition DWORD, 
length WORD, 

mode WORD, 
numBut BYTE, 
intAddr BYTE, 
pOverflow POINTER) *3 


These parameters shouldn’t be modified by the shell unless otherwise 
noted. The parameters of interest ares 


pBuffer A POINTER to the buffer specified by the application 
when it made the GRiD-OS call. 


length The number of bytes requested by the application. It 
is updated by the gateway driver to the actual number 
of bytes transferred. 


intAddr The GPIB address of the device with which the 
application wants to communicate. If the shell was 
not assigned an address when it was activated, this 
Parameter is NULL (OFFH). You should check for NULL 
and assign an address in that case. 


pOVer flow A POINTER to another block of parameters. You should 
set pOverflow to point to this block. The format of 


the overflow block varies as described in the 
following sections. 


‘OVERFLOW BLOCK FOR 1/0 REQUESTS 
This overflow block is used when sending ddRead, ddWrite, or 


ddDeactivate to the gateway driver; it appears as follows: 


DCL OverflowType LITERALLY * STRUCTURE ¢ 
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dataMode BYTE, 


E0Schar BYTE, 

secAddr BYTE, 

timeQut WORD)? ; @ 
dataMode The data transfer made. You should put a 0 in this 


byte if the high speed mode is desired, and a 2 if 
the low speed mode is desired. 


E0Schair In the low speed made, set this parameter to the 
character, if any, used to terminate a message. In 
the high speed mode, or if no EOS character is 
desired, set it to OFFH. 


secAddr Not used. 


timedut In the low speed mode, set this parameter to the 
length of time you want the gateway to wait before 
giving up on a request. This number is in 
milliseconds, 1.e., a time out duration of six 
seconds is specified as 46000. If the high speed mode 
is chosen, the timeout is fixed at five seconds. 


OVERFLOW BLOCK FOR SETSTATUS REQUESTS 


This averflow block is used when sending a ddSetStatus request. It 
appears as follows: g 


DECLARE gateWaySetStatus STRUCTURE ( 


mode BYTE, 
dataWord WORD) ; 
mode Get this byte to @ if you want to send a selective 


device clear (reset) to the device. You should set 
this byte to 2 when notifying the gateway driver to 
recognize service Requests from a device. 


dataWord If you want to recognize service requests from a 
device, set this word ta the identification number of 
the semaphore that is to be signaled. When doing a 
selective device clear, ignore this parameter. 


NOTE: ParamListType and OverflawType are defined in an Include file 


-- PrinterDriver.Inc. GateWaySetStatus should be defined in 
the shell. 
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SERVICE REQUESTS 


Some devices can interrupt the computer by asserting the Service Request 

© line. Typically, service requests are used by a device to indicate a 
readiness to transfer data or to report an error. If the gateway driver 
has been notified to recognize service requests for a device and one 
gccurs, the driver will: 


i. Poll the bus to determine which device requested service. 


2. Read a status byte from the requesting device. 

3. Signal « semaphore and pass the status byte through the semaphore 
note. You must create the semaphore and pass the semaphore 
identification number to the gateway driver with ddSetStatus request, 
mode two, 2 


There are two major uses for service requests: 


o The service request is used to report a readiness to transfer data. 
Some devices require a command to be written ta them before they can 
transfer data. For example, a device might need a cammand sent to it 
before if will transmit. In the ddRead section of the shell, you 
would write the command to the device and then wait for a service 
request before reading from the device. 


o The service request is used to report an asychronous event. In this 
case, the application should check for the signal. For example, the 
device might generate a service request when it detects an error 

|] condition. Your application could have a process waiting for an error 
signal and then take appropriate action. 


Service requests are very device-dependent and many devices do nat 
support them. If they do, they may need to be programmed to supply a 
service request. Check your device manual for details. 


When the shell receives a ddDeactivate request, delete the semaphore and 
pass a ddDeactivate request to the gateway driver. This will inform it 
ta stop responding to service requests from this device. 
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PROGRAMMING THE GPIB GATEWAY DRIVER EXAMPLES 


This section contains four examples of GPIB driver programming: @ 


o Sending a selective device clear to a device. 

o Notifying the GPIB gateway driver to recognize service requests froma 
device. 

o Reading from the device. 

o Writing to the device. 


ALL the examples assume these data declarations: 


DECLARE params ParamListType; 

DECLARE overflow OverflowType: 

DECLARE plotbuf (8) BYTE; 

DECLARE gatellaySetStatus STRUCTURE ( 
mode BYTE, 
dataWord WORD) 3 


RESET THE DEVICE 


This code tells the GPIB gateway driver to send a selective device clear 
(reset) to the device at the address specified. Se 


7/4 1 the device wasn’t assigned an address when 
it was activated, assign a default one now #/ 
IF params.intAddr = OFFH THEN 
params.intAddr = 28; 


gateWaySetStatus.mode = 0; /* Reset 4/ 

params.pOverflow = dgateWaySetStatus; 

CALL OSCALLDriver (9(5,° ‘GPIB"},0,DOUBLE (ddSetStatus), 
Qparams, error); 
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NOTIFY THE DRIVER TO RECOGNIZE SERVICE REQUESTS 


This example is for an HP 74708 plotter that requires an Input Mash (IM) 
® instruction before it will assert a SRQ. IM is an HP 7470A platter 
specific command. Other devices may require different cummands. 


‘* 14 the device wasn’t assigned an address when 
it was activated, assign a default one naw t/ 
IF params.intAddr = OFFH THEN 
params.intAddr = 28; 


gatellaySetStatus.made = 2; /% Set SRO mode t/ 


/& Create a semaphore to pass to the gateway driver ¥/ 
gateWaySetStatus.dataWord = OsCreateSemaphore (9error); 
IF error = Q THEN 
DO; 
params. pOverflow = dgateWaySetStatus; 
CALL OSCALLDriver (@(5,° ‘GPIB"),0,DOUBLE (ddSetStatus), 
Oparams, error); 


/* Send the 7470 a command to enable SRB 4/ 
plotBuf = °IM,223,47; 

params.pBuffer = MplotBuf; 

params.length = 
params.pOverflow = dover flow; 

CALL OSCALLDriver (9(5,°‘GPIB*),0,DOUBLE (ddWrite), 


Oparams, derror) ; 
& END; 


READ FROM THE DEVICE 


This example assumes the device has GPIB address 28, uses the low speed 
transfer method and terminates messages with a carriage return (ODH). 


Overflow.dataMode = 2; /* Low Speed mode */ 
Overflow.EOSchar = ODH; /% Terminate message on CR &/ 
params. pOverflow = d0verflow; 
/k-1f the device wasn’t assigned an address when 

it was activated, assign a default one now %/ 
IF params.intAddr = OFFH THEN 

params.intAddr = 29; 
CALL OSCALLDriver (9(5,°‘*GPIB’),0,DOUBLE (ddRead), 

Sparams,@errar)s 
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WRITE TO THE DEVICE 


This example assumes the device has GPIB address 28, and uses the high 
speed transfer method. 


Over¢iow.dataMode = Oo; /* High Speed mode */ 
Overflow.EDSchar = OFFH; /*k No EOS char in this mode */ 
params. pOverflow = 20verflow; 
/* If the device wasn’t assigned an address when 

it was activated, assign a default one now */ 
IF params.intAddr = OFFH THEN 

params.intAddr = 28; 
CALL OSCALLDriver (9(5,**GPIB?),0,DOUBLE (ddWrite), 

Dparams,@error): 
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GPIB SHELL EXAMPLE 


S$NOLIST LARGE OPTIMIZE(3) 


/% Generic GPIB Read and Write Shell 

Default GPIB address: 29. 

No Service Requests. 

High Speed data transfer mode. 

Default TimeOut: 5S seconds -- Fixed in High Speed Mode. 
af 


GenericGPIBDriver: DO; 
SINCLUDE (‘wO‘Incs “FimLit. Inc*Text™) 
SINCLUDE (FrinterDriver.Inc’Text™) 


DCL defaultAddress LIT *287’s- 
DCL H2SpeedMode LETS VOR 


/* Initialize the parameters in the Overflow Block 4*/ 
DCL overflow QverflowType INITIAL (HiSpeedMade, OFFH, 
OFFH, OFFFFH); 


Osbevice: PROCEDURE (request, pParams, pError) PUB REENT; 
DCL request WORD; 
DCL pParams PTR; 
DCL pError PTR; 


BCL error BASED pError WORD; 
DCL params BASED pParams ParamListType; 


DCL pSetStatus PTR; 

DCL setStatus BASED pSetStatus SetStatusType; 
DCL StatusBlock SetStatusType; 

DCL getStatus GetStatusType; 

DCL getStatusLength WORD; 


IF request = ddWrite THEN 
CALL SendToGPIB (params); 
ELSE 
IF request = ddSetStatus THEN 
Da; 
pSetStatus = params.pBuffer; 
IF setStatus.setStatMode = setTimeout 
THEN overflow.timeout = setStatus.setNewTime; 
ELSE error = notSupported; 
END; 
ELSE 
IF request = ddGetStatus THEN 
DO; 
CALL SETB (0, @getStatus, SIZE (getStatus)); 
getStatus.apen openStats 
getStatus. access accessStat; 
getStatus. GPIBAddr params. intAddr; 


unn 
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IF params.iength “ SIZE (getStatus) 
THEN getStatusLength = parans.lengths 
ELSE getStatusLength = SIZE (getStatus); 
CALL MOVE (agetStatus, params.pBuffer, getStatusLength)s 


END; e 
ELSE 


IF request = ddRead THEN 
bo; 
/* If no address was assigned when attached, 
use the default address */ 
IF params.intAddr = OFFK THEN 
params.intAddr = defaultAddress; 
params. pOverflow = Soverflow; 
CALL OSCALLDriver (9(5,° ‘GPIB"),0,DOUBLE (ddRead), 


Dparams,Derror); 

END; 

Et. SE 

IF NOT ((request = ddOpen) OR 
(request = ddInitralize) OR 
«request = ddClose) OR 
(request = ddDetach) OR 
(request = ddAttach) OR 
(request = ddTruncate} OR 
irequest = ddDeactivate)) THEN 


error = notSupported; 
END; 
WriteString: PROC (pString) REENT; 


DCL pString PTR; 
DCL string BASED pString STRUCTURE (len BYTE, chars (1) BYTE); @ 
DCL intParams ParamListType; 


intParams.pBuffer = Ostring.chars; 
intFarams. length string.len; 
CALL SendToGPIE (dintParams) ; 

END; 


SendToGPib: PROC (pParams) REENT; 
DCL pParams PTRs 
BCL params BASED pParams ParamListType; 
DCL error WORD; 


IF params.length > 0 THEN 
Da; 
/* If no address was assigned when attached, 
use the default address x/ 
IF params.intAddr = OFFH THEN 
Params.intAddr = defaultAddress; 
params.pOverflow = doverflow; 
CALL OSCALLdriver (9(5,*‘GPIB7), QO, DOUBLE (ddWrite), 
@params, @error); 


END; 
END; 
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END; /¥ Module ¥/ 
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GENERIC | 


SNOLIST LARGE OPTIMIZE(3) 


/* Generic GPIB Shell with "hooks" for Service Requests 
Default GPIB address: 28. 
High Speed Mode. 

as 


GenericGPIBDriver: DO; 


SINCLUDE ('wO‘Incs‘*PlmLit. Inc*Text™) 
$INCLUDE (PrinterDriver.Inc*Text™) 


/* Declarations for GS Procedures not in 
PrinterDriver.Inc*Text’ %/ 


QsSignal: PROCEDURE (sid, mode, note, pError) EXTERNAL; 
DCL sid WORD; 
DCL mode BYTE; 
BCL note WORD; 
DCL pError PTR; 
END; 


OsRegisterName: PROCEDURE (pName, token, made, pError) EXTERNAL; 
DCL (pName, pError) PTR; 
DCL token DWORD; 
DCL mode BYTE; 
END; 


OsWaits PROCEDURE (sid,time,pError) WORD EXTERNAL; 
DCL sid WORD, 

time WORD, 

pError PTR; 
END; 


OsCreateSemaphore: PROCEDURE (pError) WORD EXTERNAL; 
DCL pErraor PTR; 
END; 


OsDeleteSemaphore: PROCEDURE (sid,pErrar) EXTERNAL; 
DCL sid WORD, 

pError PTR; 
END; 


DEL defTimeout LIT *5000°; /% five seconds */ 
DCL defaultAddress LIT * 28°; 
DCL HiSpeedMode LIT 70°; 


DCL overflow OverflowType INITIAL (HiSpeedMode, OFFH, GFFH, 
defTimeout) ; 


DCL firstimeThru BYTE INITIAL (OFFH)$ 
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DCL Note WORD; 


DCL gateWaySetStatus STRUCTURE (mode BYTE, 
dataWord WORD); 


OsDevice: PROCEDURE (request, pParams, pError) PUB REENT; 
DCL request WORD; 
DCL pParams PTR; 
DCL pError PTR; 


DCL error BASED pError WORD; 
DCL params BASED pParams ParamListType; 


DCL pSetStatus PTR; 

DCL setStatus BASED pSetStatus SetStatusType; 
DEL StatusBlock SetStatusType; 

DEL getStatus GetStatusType; 

DEL getStatusLength WORD; - 


IF request = ddWrite THEN 
CALL SendToGPIB (dparams); 
ELSE 
IF request = ddSetStatus THEN 
DG; 
pSetStatus = params.pBuffer; 
IF setStatus.setStatMade = setTimeout 
THEN overflow. timeout = setStatus. setNewTime; 
ELSE error = notSupported; 


END; 
ELSE 
IF request = ddGetStatus THEN 
BOs 
CALL SETB (0, dgetStatus, SIZE (getStatus)); 
getStatus. open = openStat; 
getStatus.access = accessStat; 
getStatus.GPIBAddr = params.intAddr; 


IF params.length < SIZE (getStatus) 
THEN getStatusLength = params. length; 
ELSE getStatusLength = SIZE (getStatus); 
CALL MOVE (QgetStatus, params.pBuffer, getStatusLength); 


END; 
ELSE 
IF request = ddRead THEN 
DO; 
IF error = © THEN 
DO; 
IF params.intAddr = OFFH THEN 
params.intAddr = defaultAddress; 


params.pOverflaw = doverflow; 


CALL OSCALLDriver (9(5,°°GPIE’),0,DOUBLE (ddRead) ’ 
Qparams,derror); 
END; 
END; 
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ELSE IF request = ddInitialize THEN 
DO; 


¢# Tell the GPIB gateway driver to respond to SRO for this device. t/ 


OFFH THEN 
defaultAddress; 


IF params.intAddr 
params, intAddr 


IF firstimethra THEN 
DO; 
gateWaySetStatus.mode = 2; /% Set SRO #/ 


7% Create the semaphore that the gateway driver 
will Signal when a SRO is asserted by the 
device. Lia 


gateWaySetStatus.dataWord = 
OsCreateSemaphore (derror); 


IF error = 0 THEN 
Da; 
params.pOverflow = dgateWaySetStatus: 
CALL OSCALLDriver (9(5,*"GPIE*), 
O, DOUBLE (ddSetStatus), 
Oparams,derror); 
firstimeThru = FALSE; 


/¢*% Register the semaphore ID so an application can 
wait for a signal to this semaphore. %/ 


CALL OsRegisterName (9(8,’gpibSema’), 
gatewaysetstatus.dataword, 
1, 


@error); 
END; 
END; 
END; 
ELSE IF request = ddDeactivate THEN 
DO; 
IF params.intAddr = OFFH THEN 
Params.intAddr = defaultAddress; 


params. pOverflow = doverflow; 


/* Tell the gateway driver to stop responding to 


Service Requests from this device. a/ 
CALL OSCALLDriver (9(5,* ‘GPIB*),0,DOUBLE (ddDeactivate), 
Oparams,derrar); 


CALL OsDeleteSemaphore (gatewaysetstatus.dataWord, derror); 
/* Remove the name from the name table %/ 


CALL OsRegisterName (9(8,“gpibSema’), 
gatewaysetstatus. dataword, 
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5 


Serrur): 


END; 

ELSE 

TF NOT (request = ddOpen) OR 
(request = ddClose) OR 
{request = ddDetach) OR 
(request = ddAttach) OR 
(request = ddTruncate}) THEN 


error = notSupsorted; 
END; 
WriteString: PROC (pString) REENT; 
DCL pString FTIR} 
DCL string BASED pString STRUCTURE (len BYTE, chars (i) BYTE); 
DCL intParams ParamListType: 


intParams.pButfer = dstring.chars; 


intParams.length = string.len; 
CALL SendToGPIB (3intParams) ; 
END; 


SendToGPIB: PROC (pParams) REENT; 
.DCL pParams PTR; 
DCL params BASED pParams ParamListType; 
DCL error WORD; 


IF params.length > 0 THEN 


Da; 
IF error = 0 THEN 
DO; 


IF params.intAddr = OFFH THEN 
Params.intAddr = defaultAddress; 
params. pOverflow = doverflow; 
CALL OSCALLdriver (9(5,°‘GFIB'), 9, 
DOUBLE (ddWrite), params, 
@error); 
END; 
END; 
END; 


END; /% Module x/ 
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GENERIC _SPIB_DEVELOP FIL! 


GenericGPIB 
Gener ic&PIB 
"WO ‘LST * 
:Objects: "WO ‘OBI © 


Sources: 
GenericGPIB.Plm 
GenericGPIBSR@. Flim 


:Control Yes w/Debug: DEBUG 


tLink GenericGPIB: 

LINK 

*wO ‘OBJ ‘GenericGPIB.PLM”OBJ™, ‘w0 ‘Libs ‘JmpDev. Asm™Ob j”, ‘w0 ‘Libs ‘LargeSing} 
eException.Asm™Ob j™, ‘wO ‘Libs *LargeSystemCalils*Lib™ TO GenericGPIB™Device™ 
BIND SS(STACK(G)) PC(PURGE) FASTLOAD PURGE 

PRINT ( ‘wO ‘LST *GenericGPIB*MP1™) 


sLink GenericGPIB SRG: 

LINK 

‘wO *OBJ ‘Gener i cGPIBSRQ. PLM*OBJ™, ‘wO ‘Libs ‘ImpDev.Asm™0b j”, ‘wO ‘Libs ‘LargeSi 
ngleException.Asm*0bj”, ‘wO‘Libs ‘LargeSystemCalls*Lib™ TO 
GenericGPIBSRO*Device™ BIND SS{STACK(O)) PC(PURGE) FASTLOAD PURGE 

PRINT ( wO ‘LST ‘GenericGPIBSRO~MP1™) 


sTest GenericGPIB: 
Deactivate GenericGPIB 
Activate GenericGPIB 28 


sTest GenericGPIB SRQ: 
Deactivate GenericGPIBSRO 
Activate GenericGPIBSRO 2B 


Command Line: 
*DevelopmentExecutive’ 


:GRiDManager: 
?GRiDManager* 
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This appendix defines the GRiD Universal Printer Interface Language. It 
defines the interface between any application which supports printing and any 
GRiD supported printer driver. 


Applications should attach to ‘Printer. GRiD-OS will be responsible for 
mapping this into the current system printer. When opened, the driver 
initializes the printer inte its normal typeface (12 pitch). When closed, the 
driver flushes the printer’s internal buffer. 


The commands which each printer must support (support can mean to ignore) are 
listed below. The driver must accept these codes in a serial byte stream. 


Command Turn on/off 


Pass an ESC thru ESC ESC 


Boldface ESC *B* 
Underline Esc *u’ 
Italics Esc *r° 
Superscript ESC *+" 
Subscript ESC °-? 
Enlarged ESC *E’ 
Condensed Ese *C* 
Line spacing ESC UP 7 


Where n is in 1/8ths of an line. ( 8/8 = single line spacing } 
Graphics ESC °G’ width height topLeft.x topLeft.y nextRow 
NOTE: When using sub ar superscripts, the line Spacing must be set to a value 
greater than single line spacing to aliow room. 


NOTE: Turning subscripting (superscripting) on automatically turns 
superscripting (subscripting) off. 


Universal Printer Language A-i 


In addition, each driver must suppurt a command to print screen images. This 
is impossible for letter quality printers but they must skip the appropriate 
amount of “white space" so that an image could be pasted in later. 


ESC ’G’ width height topleft..x topleft.y nextRow @ 


The five parameters are word values and are explained in the following 
diagram. All parameters are in pixels units. The values to print a normal 


Screen image are: 


320, 240, 0, 0, 320 


A-2 Device Drivers 


OPPENDIY | 


This section lists the error codes that can result fram calling a gateway 


driver, 


Serial Gateway Driver 


O: 


35: 


401; 


Everything OK. No action necessary. 


Request Not Supported. You asked the gateway driver to do something 
impossible. For example, the serial driver does not support a seek 
request. 


Device Not Active. This error can occur in three situations: 


1. 


2. 


3. 


The serial device has not been activated. Be sure you have 
activated Serial™Device™ from the command line or 
Programmatically. 

You attempted to transter data before establishing a connection. 
Make sn OsSetStatus mode six call to establish a connection. 
The gateway driver lost CTS and/or DCD. You can determine which 
one by making a OsGetStatus call and examining the modemContral 
byte. Make sure these signals are active on your hardware or 
make an OsSetStatus mode 40 call to change the required signals. 


Bad Parameter. You Passed the gateway driver a valid request but with 
a bad parameter. For example, you would get this error if you made an 
OsSetStatus mode 44 call to the serial gateway driver. 


Time Qut Error. This error can occur in two situations. 


i 


nN 


When reading, the gateway driver did not receive a character 
within the character time out Period. Check your hardware or 
make an OsSetStatus mode two call to change the character time 
out, 


+ When establishing a connection, the gateway driver did not 


detect a handshake within the connect time out period. Check 
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your hardware. You can make en OsSetStatus mode two call to 
change the connect time oot period, or yau can make an 
OsSetStatus mode 60 call to change the required signals. 


Carrier Was Lost. Check your hardware. 2 


403; Parity Error. Make an OsSetStatus mode one request to change parity 
Lypee 


Re 


Modem Gateway Drivér 


Os Everything OK, No action necessary. 


35: Request Not Supported. You asked the gateway driver to do something 
impossible. For example, the modem driver does not support a seek 
request. J 


Q3iz Device Not Active. This error can occur in two situations: 

i. The modem device has not been activated. Be sure you have 
activated Modem™’Device” fram the command line or 
programmatically. 

2. You attempted to transfer data before establishing a connection. 
Make an OsSetStatus mode six call to establish a connection. 


25S: Bad Parameter. You passed the gateway driver a valid request but with 
a bad parameter. For example, you would get this error if you made an 
OsSetStatus made 41 call to the modem gateway driver. 


400: Madem Did Not Answer. When establishing a connection, the gateway a 
driver did not detect a handshake within the connect time out period. 
You can change the connect time out period with OsSetStatus mode two. 

401: Time Qut Error. When reading, the gateway driver did not receive a 
character within the character time out period. You can adjust the 
character time out period with OsSetStatus mode two. 

402: Carrier Was Lost. 


403: Parity Error. Make an OsSetStatus mode one request to change parity 
type. 


404: Bad Phone Number. You asked the modem driver to dial a number that 
contained illegal characters. Only numbers ar format characters are 
allowed. 14 you are using touchtone dialing, the "#" or Es Sud 
characters are also allowed. 


GPIB Gateway Driver 


Q: Everything OK. No action necessary. 
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451: 


AS2: 


Request Not Supported. You asked the gateway driver to do something 
impossible, For example, the GPIB driver only supports set status 
modes af zero or two, Other requests will return this error. 


GPIB Time Out. When reading, the gateway driver did not receive a 
Character within the time out period. If you are using the low speed 
mode, you can adjust the time out period in the parameter block. 


GPIB Not Responding. The gateway driver could not communicate with 
the other device. He sure the other device is turned on and ready. 


Error Codes B-3 


